Host-Target Break-In Analysis

You can use WinDbg to break into RTX64 on a remote target machine and make extension calls to get status information. When you break into a target system, all the processors/cores (including those partitioned for RTSS) are frozen.

Two machines are required for breaking in with WinDbg: a host machine and a target machine. The host machine contains the RTX64 SDK and runs WinDbg with the RTX64 Extension loaded. The target machine contains the RTX64 Runtime and executes the RTSS processes to be analyzed. The machines can be connected with a WinDbg supported cable. This topic provides brief setup descriptions for some common connection types. For more information, see MSDN http://msdn.microsoft.com/en-us/library/windows/hardware/hh439378(v=vs.85).aspx .

This topic explains how to set up a host-target environment.

NOTE: Use of int3 or breakpoints to break a target is not supported.

NOTE: This scenario does not support stepping-through code.

Connecting to the Target and Breaking-In

To connect to the Target:

1. Make sure the two machines are connected.
2. On the host, open WinDbg. To do this, click Start > Debugging Tools for Windows (x64) > WinDbg.
3. Select Kernel Debug from the File menu.
4. Configure the type of connection you want to use:

For COM connections:

1. Click the COM tab.
2. Enter the Baud Rate and Port you want to use. Click OK.
   
   

NOTE: The Kernel Debugging dialog on Windows 7 is shown. On Windows 8.1, the COM tab is on the far right.

For IEEE 1394 (Firewire) connections:

1. Click the 1394 tab.
2. Enter the Channel you want to use and click OK. The channel specified here must match the channel specified during Target set up (see Configuring the Target Machine above).
   
   

NOTE: The Kernel Debugging dialog on Windows 7 is shown. On Windows 8.1, the 1394 tab is to the right of the USB tab.

For more information, see MSDN http://msdn.microsoft.com/en-us/library/windows/hardware/hh439378(v=vs.85).aspx.

5. Click Yes to save information for the workspace.
6. WinDbg is now ready to connect to the target machine. The WinDbg window indicates this status with the message waiting to reconnect.
   
   Select Verbose Output from the View menu. This option causes more detailed output to be displayed in the debugger command window. For example, with Verbose Output set, WinDbg displays every driver or DLL that Windows loads.
7. You can now break into the target machine (assuming it has been set up to be debugged).

To break into the target machine:

1. On the target system, start the RTX64 Subsystem and run your RTSS application.
2. Back on the host machine, in the WinDbg window, select Debug > Break or press CONTROL + BREAK. You will see a message similar to the following and your target system will halt and become unresponsive:
   
   

3. Load the RTX64 WinDbg Extension. To do this, type the following at the debugger command prompt:

.load RtDbgExt.dll

NOTE: You do not need to load the WinDbg Extension for subsequent break-ins.

If the above command fails to load the RtDbgExt.dll, include the full path to the location of the DLL:

 

.load %RTX64SDKDir3%\WinDbgExtension\rtdbgext.dll

4. Call RTX64 WinDbg Extension commands to analyze the system. For example, call !rtprocess to list the RTSS processes currently running on the system.
5. Once you have finished analyzing the system, resume normal operation on the target system. To do this, do one of the following:

• Type G at the kd> prompt, or
• Select Go from the Debug menu in WinDbg, or
• Press the F5 key.

The target machine should no longer be halted and the target keyboard and mouse should be responsive.

To run RTX64 WinDbg Extension Commands:

Once the RTX64 WinDbg Extension is loaded, you can use any of the supported WinDbg Extension commands. To do this, type the command at the debugger command prompt. For example:

!rtversion

For the complete list of supported commands, see RTX64 WinDbg Extension Commands Reference.

Quick Start: Breaking into the Target Machine

When you break into a target system, all the processors/cores (including those partitioned for RTSS) are frozen. You can display the content of a variable or a data structure for which you know the virtual address on the target system. By loading RtDbgExt.dll, you can display extended information on the target system, including active RTSS processes and information on the Subsystem in general.

Below are a few recommended steps for break-in analysis of a target system.

• Use !rtprocess without parameters to display the active RTSS processes.
• Use !rtcurrentprocess to display the current processes running on RTSS processors.
• To display the extended information for a specific process, use !rtprocess and specify the process object address or PID.
• For information on memory usage, use !rtmemory or !rtlocmem to display the allocated memory list within the specified process.
• To check the fragmentation of RTSS local memory pool, use !rtlocmempool /f.
• For information on object states, use !rtobject to list all the objects within the Subsystem. By specifying the object address as a parameter for !rtobject, you can see the extended information of that object.

For more information on using commands, see using Using WinDbg Extension Commands.

Related topics:

• Setting Up a System to Use the RTX64 WinDbg Extension
• WinDbg Debugging Tips
• Using Windows Dump Files for Postmortem Analysis
• RTX64 WinDbg Extension Commands Reference